This chapter provides information about the Remote Statistics Interface.
An application programming interface (API) is available for those who want to develop programs that access the statistics available from one or more xmservd daemons. The API is called the Remote Statistics Interface or the RSI Interface. This chapter describes how you use the RSI Interface API by walking you through a couple of sample programs. Those sample programs, and others, are provided in machine-readable form as well. The sample programs can be found in the directory:
/usr/samples/perfmgr
You use the RSI Interface API to write programs that access one or more xmservd daemons. This allows you to develop programs that print, post-process, or otherwise manipulate the raw statistics provided by the xmservd daemon(s). Such programs are known as Data-Consumer programs.
The include files are based upon a number of define directives being properly set. They are normally defined with the -D preprocessor flag. The following define directives should be in effect for compiling on AIX Version 3.2 and AIX Version 4.
A Makefile to build all the sample programs provided could look like the one shown in the listing below:
LIBS = -L./ -lbsd -lSpmi
CC = cc
CFLAGS = -D_BSD -D_AIX
all:: RsiCons RsiCons1 chmon
RsiCons: RsiCons.c
$(CC) -o RsiCons RsiCons.c $(CFLAGS) $(LIBS)
RsiCons1: RsiCons1.c
$(CC) -o RsiCons1 RsiCons1.c $(CFLAGS) $(LIBS)
chmon: chmon.c $
$(CC) -o chmon chmon.c $(CFLAGS) $(LIBS) -lcurses
If the system you compile on doesn't support ANSI function prototypes. add the following flag:
-D_NO_PROTO
As interesting and useful as it may be to watch the graphics display of statistics shown by xmperf, many other uses of the wealth of statistics are available through the xmservd daemons on all the hosts in a network. The Remote Statistics Interface API allows you to create data-consumer programs that can get full access to the statistics of any host's xmservd daemon.
The RSI interface consists of several groups of subroutines as follows:
| RSiInit | Allocates or changes the table of RSI handles. |
| RSiOpen | Initializes the RSI interface for a remote host. |
| RSiClose | Terminates the RSI interface for a remote host and releases all memory allocated. |
| RSiInvite | Invites data suppliers on the network to identify themselves and returns a table of data-supplier host names. |
| RSiInstantiate | Creates (instantiates) all subcontexts of a context object. |
| RSiPathGetCx | Searches the context hierarchy for a context that matches a context path name. |
| RSiFirstCx | Returns the first subcontext of a context. |
| RSiNextCx | Returns the next subcontext of a context. |
| RSiFirstStat | Returns the first statistic of a context. |
| RSiNextStat | Returns the next statistic of a context. |
| RSiAddSetHot | Adds a single set of peer statistics to a hotset. |
| RSiCreateHotSet | Creates an empty hotset. |
| RSiCreateStatSet | Creates an empty statset. |
| RSiPathAddSetStat | Adds a single statistic to a statset. |
| RSiDelSetHot | Deletes a single set of peer statistics from a hotset. |
| RSiDelSetStat | Deletes a single statistic from a statset. |
| RSiStatGetPath | Finds the full path name of a statistic identified by an SpmiStatVals pointer. |
| RSiStartFeed | Tells xmservd to start sending data feeds for a statset. |
| RSiStartHotFeed | Tells xmservd to start sending hot feeds for a hotset. |
| RSiChangeFeed | Tells xmservd to change the time interval between sending data feeds for a statset. |
| RSiChangeHotFeed | Tells xmservd to change the time interval between sending hot feeds for a hotset. |
| RSiStopFeed | Tells xmservd to stop sending data feeds for a statset. |
| RSiStopHotFeed | Tells xmservd to stop sending hot feeds for a hotset. |
| RSiGetHotItem | Returns the peer context name and data value for the first (next) SpmiHotItems element by extraction from data feed packet. |
| RSiMainLoop | Allows an application to suspend execution and wait to get waked up when data feeds arrive. |
| RSiGetValue | Returns data value for a given SpmiStatVals pointer by extraction from data feed packet. |
| RSiGetRawValue | Returns a pointer to a valid SpmiStatVals structure for a given SpmiStatVals pointer by extraction from data feed packet. |
Before you start using the RSI interface API you need to be aware of the format and use of the RSI interface data structures. This section explains the structures and also introduces you to the commonalities of the library functions and to some important design concepts. This section has the following subsections:
The RSI interface is based upon control blocks (data structures) that describe the current view of the statistics on a remote host and the state of the interaction between a data consumer program and the remote host's xmservd daemon. Data structures to know about are:
RSI handle
An RSI handle is a pointer to a data structure of type
RSiHandleStruct.
Prior to using any other RSI call, a data-consumer program must use the
RSiInit subroutine to allocate a table of
RSI handles. An RSI handle from the table is initialized when you open
the logical connection to a host and that RSI handle must be specified
as an argument on all subsequent subroutines to the same host. Only one
of the internal fields of the RSI handle should be used by the data-consumer
program, namely the pointer to received network packets, pi. Only
in very special cases will you ever need to use this pointer, which is
initialized by RSiOpen and must never be
modified by a data-consumer program. If your program changes any field
in the RSI handle structure, results are highly unpredictable. The RSI
handle is defined in /usr/include/sys/Rsi.h.
SpmiStatVals
A single data value is represented by a structure defined in
/usr/include/sys/Spmidef.has struct SpmiStatVals. You should be aware that none of
the fields defined in the structure must be modified by application programs.
The two handles in the structure are symbolic references to contexts and
statistics and should not be confused with pointers. The last three fields
are updated whenever a data_feed packet is received. These fields
are:
Note that the two value fields are defined as union Value, which means that the actual data fields may be long or float, depending on flags in the corresponding SpmiStat structure. The SpmiStat structure can not be accessed directly from the StatVals structure (the pointer is invalid, as already mentioned). Therefore, to determine the type of data in the val and val_change fields, you must have saved the SpmiStat structure as returned by the RSiPathAddSetStat subroutine. This is rather clumsy so the subroutine RSiGetValue does everything for you and you needn't worry about keeping track of SpmiStat structures.
SpmiStat
This is a data structure to describe a statistic. It is defined
in /usr/include/sys/Spmidef.h as type struct SpmiStat.
If you ever need information from this data structure (apart from information
that can be returned by the subroutine RSiStatGetPath
) be sure to save it as it is returned by the RSiPathAddSetStat
subroutine.
The RSiGetRawValue subroutine provides another way of getting access to an SpmiStat structure but can only do so while a data feed packet is being processed.
SpmiStatSet
The xmservd daemon accepts the definition of sets of statistics
that are to be extracted simultaneously and sent to the data-consumer program
in a single data packet. The structure that describes such a set of statistics
is defined in /usr/include/sys/Spmidef.h as of type struct
SpmiStatSet. As returned by the RSiCreateStatSet
subroutine, the SpmiStatSet pointer should be treated as a handle
whose only purpose is to identify the correct set of statistics to several
other subroutines.
When returned in a data feed packet, the SpmiStatSet structure holds the actual time the data feed packet was created (according to the remote host's clock) and the elapsed time since the latest previous data feed packet for the same SpmiStatSet was created.
SpmiHotSet
Represents another set of access structures that allow an application
program to define an alternative way of extracting and processing metrics.
They are used to extract data values for the most or least active statistics
for a group of peer contexts. For example, it can be used to define that
the program wants to receive information about the two highest loaded disks,
optionally subject to the load exceeding a specified threshold.
When the SPMI receives a read request for an SpmiHotSet, the SPMI reads the latest value for all the peer sets of statistics in the hotset in one operation. This action reduces the system overhead caused by access of kernel structures and other system areas, and ensures that all data values for the peer sets of statistics within a hotset are read at the same time. The hotset may consist of one or many sets of peer statistics.
SpmiHotVals
One SpmiHotVals structure is created for each set of peer
statistics selected for the hotset. When the SPMI executes a request from
the application program to read the data values for a hotset, all
SpmiHotVals
structures in the set are updated. The RSi application program can then
traverse the list of SpmiHotVals structures by using the RSiGetHotItem
subroutine call.
The SpmiHotVals structure carries the data values from the SPMI to the application program. Its data carrying fields are:
The RSI interface API has two distinctly different ways of operation. This section describes the RSI "request-response" protocol that sends a single request to xmservd and waits for a response. A timeout occurs if no response has been received within a specified time limit in which case one single retry is attempted. If the retry also results in a timeout, that fact is communicated to the caller by placing the constant RSiTimeout in the external integer field RSiErrno. If any other error occurred, the external integer field has some other non-zero value.
If neither a communications error nor a timeout occurred, a packet is available in the receive buffer pointed to by the pi pointer in the RSI handle. The packet includes a status code that tells whether the subroutine was successful at the xmservd side. You need only be concerned with checking the status code in a packet if it matters what exactly it is because the constant RSiBadStat is placed in RSiErrno to indicate to your program that a bad status code was received.
You can use the indication of error or success as defined for each subroutine to determine if the subroutine succeeded or you can test the external integerRSiErrno. If this field is RSiOkay the subroutine succeeded; otherwise it did not. The error codes returned in RSiErrno are defined in the enum RSiErrorType.
All the library functions use the request-response interface, except for RSiMainLoop (which uses a network driven interface) and RSiInit, RSiGetValue, and RSiGetRawValue (that do not involve network traffic).
The xmquery protocol, which is described in detail in "The xmservd Interface", defines three types of data packets that are sent from the data supplier side (xmservd) without being solicited by a request packet. Those packet types are the still_alive, the data_feed, and the except_rec packets. The still_alive packets are handled internally in the RSI interface and require no programming in the data-consumer program.
The data_feed packets are received asynchronously with any packets produced by the request-response type subroutines. If a data_feed packet is received when processing a request-response function, control is passed to a callback function, which must be named when the RSI handle is initialized with the RSiOpen subroutine.
When the data-consumer program is not using the request-response functions, it still needs to be able to receive and process data_feed packets. This is done with the RSiMainLoop function, which invokes the callback function whenever a packet is received.
Actually, the data feed callback function is invoked for all packets received that can not be identified as a response to the latest request sent, except if such packets are of type i_am_back, still_alive, or except_rec. Note that this means that responses to "request-response" packets that arrive after a timeout is sent to the callback function. It is the responsibility of your callback function to test for the packet type received.
The except_rec packets are received asynchronously with any packets produced by the request-response type subroutines. If an except_rec packet is received when processing a request-response function, control is passed to a callback function, which must be named when the RSI handle is initialized with the RSiOpen subroutine.
When the data-consumer program is not using the request-response functions, it still needs to be able to receive and process except_rec packets. This is done with the RSiMainLoop function which invokes the callback function whenever a packet is received.
Note that the API discards except_rec messages from a remote host unless a callback function to process the message type was specified on the RSiOpen subroutine call for that host.
Network connections can go bad, hosts can go down, interfaces can be taken down and processes can die. In the case of the xmservd protocol, such situations normally result in one or more of the following:
It is important that you understand how the xmservd daemon handles "first time contacted." It is based upon tables internal to the daemon. Those tables identify all the data-consumers that the daemon knows about. Be aware that a data-consumer program is known by the host name of the host where it executes suffixed by the IP port number used to talk to the daemon. Each data-consumer program running is identified uniquely as are multiple running copies of the same data-consumer program.
Whenever a data-consumer program exits orderly, it alerts the daemon that it intends to exit and the daemon removes it from the internal tables. If, however, the data-consumer program decides to not request data feeds from the daemon for some time, the daemon detects that the data consumer has lost interest and removes the data consumer from its tables as described in "Life and Death of xmservd" on page . If the data-consumer program decides later that it wants to talk to the xmservd again, the daemon responds with an i_am_back packet.
The i_am_back packets are given special treatment by the RSI interface. Each time one is received, a resynchronizing callback function is invoked. This function must be defined on the RSiOpen subroutine.
Please note that all data-consumer programs can expect to have this callback invoked once during execution of the RSiOpen subroutine since the remote xmservd does not know the data consumer. This is normal and should not cause your program to panic. If the resynchronize callback is invoked twice during processing of the RSiOpen function, the open failed and can be retried, if appropriate.
In this section, we illustrate the use of the API by creating a small data-consumer program to produce a continuous list of statistics from a host. The first version accesses only CPU-related statistics. It assumes you want to get your statistics from the local host unless you specify a host name on the command line. The program continues to display the statistics until it is killed. Source code for the sample program can be found in /usr/samples/perfmgr/RsiCons1.c.
The main function of the sample program uses the three subroutines as shown in the code segment below. The lines 12 through 15 use any command line argument to override the default host name obtained by the uname function. Then lines 17 through 28 initialize the RSI interface using the RSiInit and RSiOpen subroutines. The program exits if the initialization fails.
[01] extern char RSiEMsg[];
[02] extern int RSiErrno;
[03] char host[64], apath[256], head1[24][10], head2[24][10];
[04] char *nptr, **navn = &nptr, *dptr, **desc = &dptr;
[05] struct utsname uname_struct;
[06] RSiHandle rsh;
[07] struct SpmiStatVals *svp[24];
[08] int lct = 99, tix = 0;
[09]
[10] main(int argc, char **argv)
[11] {
[12] uname(&uname_struct);
[13] strcpy(host, uname_struct.nodename);
[14] if (argc > 1)
[15] strcpy(host, argv[1]);
[16]
[17] if (!(rsh = RSiInit(1)))
[18] {
[19] fprintf(stderr, "Unable to initialize RSI interface\n");
[20] exit(98);
[21] }
[22] if (RSiOpen(rsh, 100, 2048, host, feeding, resync, NULL))
[23] {
[24] if (strlen(RSiEMsg))
[25] fprintf(stderr, "%s", RSiEMsg);
[26] fprintf(stderr, "Error contacting host
\"%s\"\n", host);
[27] exit(-99);
[28] }
[29] signal(SIGINT, must_exit);
[30] signal(SIGTERM, must_exit);
[31] signal(SIGSEGV, must_exit);
[32] signal(SIGQUIT, must_exit);
[33]
[34] strcpy(apath, "hosts/");
[35] strcat(apath, host);
[36] strcat(apath, "/");
[37] lststats(apath);
[38] RSiClose(rsh);
[39] exit(0);
[40] }
The following lines (29-32) make sure that the program detects any attempt to kill or terminate it. If this happens, the function must_exit is invoked. This function has the sole purpose of making sure the association with the xmservd daemon is terminated. It does this as shown in the following piece of code:
void must_exit()
{
RSiClose(rsh);
exit(-9);
}
Finally, lines 34 through 36 prepare an initial value path name for the main processing loop of the data-consumer program. This is the way all value path names should be prepared. After doing this, the main processing loop in the internal function lststats is called. If, against odds, this function returns, we issue an RSiClose call and exit the program.
It is the intention that our sample data-consumer program eventually is able to receive data feeds from the xmservd daemon so we might as well start preparing the SpmiStatSet, which defines the set of statistics we are interested in. This is done with the RSiCreateStatSet subroutine .
[01] voidlststats(char *basepath)
[02] {
[03] struct SpmiStatSet *ssp;
[04] char tmp[128];
[05]
[06] if (!(ssp = RSiCreateStatSet(rsh)))
[07] {
[08] fprintf(stderr, "RsiCons1 can\'t create StatSet\n");
[09] exit(62);
[10] }
[11]
[12] strcpy(tmp, basepath);
[13] strcat(tmp, "CPU/cpu0");
[14] if ((tix = addstat(tix, ssp, tmp, "cpu0")) == -1)
[15] {
[16] if (strlen(RSiEMsg))
[17] fprintf(stderr, "%s", RSiEMsg);
[18] exit(63);
[19] }
[20]
[21] RSiStartFeed(rsh, ssp, 1000);
[22] while(TRUE)
[23] RSiMainLoop(499);
[24] }
In our sample program, the SpmiStatSet is created in the local function lststats shown above in lines 6 through 10.
Lines 12 through 19 invoke the local function addstat, which finds all the CPU-related statistics in the context hierarchy and initializes the arrays to collect and print the information. The first two lines expand the value path name passed to the function by appending CPU/cpu0. The resulting string is the path name of the context where all CPU-related statistics for "cpu0" are held. The path name has the format hosts/hostname/CPU/cpu0 without a terminating slash, which is what is expected by the subroutines that take a value path name as an argument. The function addstat is shown in the next section. It uses three of the traversal functions to access the CPU-related statistics.
[01] int addstat(int ix, struct SpmiStatSet *ssp, char *path, char *txt)
[02] {
[03] cx_handle *cxh;
[04] int i = ix;
[05] char tmp[128];
[06] struct SpmiStatLink *statlink;
[07]
[08] if (!(cxh = RSiPathGetCx(rsh, path)))
[09] {
[10] fprintf(stderr, "RSiPathGetCx can\'t access host %s (path
%s)\n", host, path);
[11] exit(61);
[12] }
[13]
[14] if ((statlink = RSiFirstStat(rsh, cxh, navn, desc)))
[15] {
[16] while (statlink)
[17] {
[18] if (i > 23)
[19] break;
[20] strcpy(head1[i], txt);
[21] strcpy(head2[i], *navn);
[22] strcpy(tmp, path);
[23] strcat(tmp, "/");
[24] strcat(tmp, *navn);
[25] if (!(svp[i] = RSiPathAddSetStat(rsh, ssp, tmp)))
[26] return(-1);
[27] i++;
[28] statlink = RSiNextStat(rsh, cxh, statlink, navn, desc);
[29] }
[30] }
[31] return(i);
[32] }
The use of RSiPathGetCx by the sample program is shown in lines 8 through 12 . Following that, in lines 14 through 30, two subroutines are used to get all the statistics values defined for the CPU context. This is done by using RSiFirstStat and RSiNextStat.
In lines 20-21, the short name of the context ("cpu0") and the short name of the statistic are saved in two arrays for use when printing the column headings. Lines 22-24 construct the full path name of the statistics value by concatenating the full context path name and the short name of the value. This is necessary to proceed with adding the value to the SpmiStatSet with the subroutine RSiPathAddSetStat . The value is added by lines 25 and 26.
The only part of the main processing function in the main section yet to explain consists of lines 21 through 23. The first line simply tells the xmservd daemon to start feeding observations of statistics for an SpmiStatSet by issuing the RSiStartFeed subroutine call. The next two lines define an infinite loop that calls the function RSiMainLoop to check for incoming data_feed packets.
There are two more subroutines concerned with controlling the flow of data feeds from xmservd. Neither is used in the sample program. The subroutines are described in RSiChangeFeed and RSiStopFeed.
Whenever a data_feed is detected by the RSI interface, the data feed callback function defined in the RSiOpen subroutine is invoked, passing the RSI handle as an argument to the callback function. Our sample program's callback function for data feeds is shown below. Most of the lines in the function are concerned with printing headings after each 20 detail lines printed. This is in line numbers 9 through 19 and 26.
[01] void feeding(RSiHandle rsh, pack *p)
[02] {
[03] int i;
[04] float f;
[05] long v;
[06]
[07] if (p->type != data_feed)
[08] return;
[09] if (lct > 20)
[10] {
[11] printf("\n\n");
[12] for (i = 0; i < tix; i++)
[13] printf("%08s", head1[i]);
[14] printf("\n");
[15] for (i = 0; i < tix; i++)
[16] printf("%08s", head2[i]);
[17] printf("\n");
[18] lct = 0;
[19] }
[20] for (i = 0; i < tix; i++)
[21] {
[22] v = RSiGetValue(rsh, svp[i]) * 10.0;
[23] printf("%6d.%d", v/10, v%10);
[24] }
[25] printf("\n");
[26] lct++;
[27] }
Actual processing of received statistics values is done by the lines 20-24. It involves the use of the library subroutine RSiGetValue. The following is an example of output from the sample program RsiCons1 when executed against an AIX Version 3.2 system.
$ RsiCons1 umbra
cpu0 cpu0 cpu0 cpu0 cpu0 cpu0 cpu0 cpu0
user kern wait idle uticks kticks wticks iticks
0.0 0.0 0.0 100.0 0.0 0.0 0.0 100.0
0.0 0.0 0.0 100.0 0.0 0.0 0.0 99.9
0.2 3.1 0.0 96.5 0.2 3.2 0.0 96.6
3.5 5.5 1.5 89.1 3.5 5.5 1.5 89.1
5.8 3.4 0.0 90.8 5.8 3.4 0.0 90.8
8.8 8.3 0.1 82.5 8.8 8.3 0.2 82.5
67.5 2.4 3.0 27.0 67.5 2.3 2.9 26.9
16.0 0.6 0.8 82.5 16.0 0.6 0.8 82.6
67.5 5.0 0.0 27.3 67.5 5.0 0.0 27.3
19.0 6.1 0.9 73.8 19.1 6.1 0.9 73.8
22.5 0.8 1.6 75.0 22.5 0.8 1.6 74.9
60.2 6.1 0.0 33.5 60.2 6.1 0.0 33.5
$
If you need to know more about the data received in data_feed packets than what RSiGetValue gives you, you can use the library subroutine RSiGetRawValue.
A slightly more capable version of the sample program discussed in the previous sections is provided as /usr/samples/perfmgr/RsiCons.c. This program also lists the statistics with the short name xfer for all the disks found in the system where the daemon runs. To do so, the program uses some additional subroutines to traverse contexts as described in the following section.
The function adddisk listed below shows how the RSiFirstCx, RSiNextCx, and the RSiInstantiate subroutines are combined with RSiPathGetCx to make sure all subcontexts are accessed. The sample program's internal function addstat is used to add the statistics of each subcontext to the SpmiStatSet in turn. A programmer who wanted to traverse all levels of subcontexts below a start context could easily create a recursive function to do this.
[01] int adddisk(int ix, struct SpmiStatSet *ssp, char *path)
[02] {
[03] int i = ix;
[04] char tmp[128];
[05] cx_handle *cxh;
[06] struct SpmiStatLink *statlink;
[07] struct SpmiCxLink *cxlink;
[08]
[09] cxh = RSiPathGetCx(rsh, path);
[10] if ((!cxh) || (!cxh->cxt))
[11] {
[12] if (strlen(RSiEMsg))
[13] fprintf(stderr, "%s", RSiEMsg);
[14] fprintf(stderr, "RSiPathGetCx can\'t access host %s (path
%s)\n",
[15] host, path);
[16] exit(64);
[17] }
[18] if (rsh->pi->data.getcx.context.inst_freq == SiContInst)
[19] {
[20] if ((i = RSiInstantiate(rsh, cxh)))
[21] return(-1);
[22] }
[23] if ((cxlink = RSiFirstCx(rsh, cxh, navn, desc)))
[24] {
[25] while (cxlink)
[26] {
[27] strcpy(tmp, path);
[28] if (strlen(tmp))
[29] strcat(tmp, "/");
[30] if (*navn)
[31] strcat(tmp, *navn);
[32] if ((i = addstat(i, ssp, tmp, *navn)) == -1)
[33] {
[34] if (strlen(RSiEMsg))
[35] fprintf(stderr, "%s", RSiEMsg);
[36] exit(63);
[37] }
[38] cxlink = RSiNextCx(rsh, cxh, cxlink, navn, desc);
[39] }
[40] }
[41] return(i);
[42] }
Below is the output from the RsiCons program when xmservd runs on an AIX Version 4.1 host.
$ RsiCons encee
CPU CPU CPU CPU hdisk3 hdisk1 hdisk0 cd0
uticks kticks wticks iticks xfer xfer xfer xfer
19.6 10.0 4.1 67.1 2.7 4.1 0.0 0.0
10.9 15.3 8.2 65.3 0.0 8.2 0.0 0.0
0.5 2.0 0.0 97.5 0.0 0.0 0.0 0.0
10.5 4.0 0.0 85.5 0.0 0.0 0.0 0.0
55.4 8.9 0.0 35.4 2.4 0.0 0.0 0.0
19.0 5.5 0.0 75.5 0.0 0.0 0.0 0.0
5.9 6.4 0.0 87.4 0.0 0.0 0.0 0.0
10.5 7.0 0.0 82.5 0.0 0.0 0.0 0.0
7.9 7.4 0.0 84.4 0.0 0.0 0.0 0.0
88.5 8.5 3.0 0.0 9.5 4.5 0.0 0.0
89.4 8.9 1.4 0.0 5.9 0.0 0.0 0.0
92.5 5.5 2.0 0.0 9.0 8.5 0.0 0.0
71.0 6.0 23.0 0.0 44.0 41.0 0.0 0.0
37.9 2.4 58.9 0.4 67.9 61.4 0.0 0.0
17.5 4.5 0.0 78.0 1.5 3.0 0.0 0.0
0.5 1.5 10.0 88.0 7.5 1.5 0.0 0.0
$
Sometimes you want to design programs that can present the end user with a list of potential data-supplier hosts rather than requiring the user to specify which host to monitor. The RSiInvite allows you to create such programs.
The RSiInvite subroutine uses one or more of the following methods to obtain the Internet addresses to which an invitational are_you_there message can be sent. The last two methods depend on the presence of the $HOME/Rsi.hosts file. PTX also has alternative locations of the Rsi.hosts file. The three ways to invite data-supplier hosts are:
The file $HOME/Rsi.hosts has a very simple layout. Only one keyword is recognized and only if placed in column one of a line. That keyword is:
nobroadcast
and means that the are_you_there message should not be broadcast using method 1 above. This option is useful in situations where a large number of hosts are on the network and only a well-defined subset should be remotely monitored. To say that you don't want broadcasts but want direct contact to three hosts, your $HOME/Rsi.hosts file might look like this:
nobroadcast birte.austin.ibm.com gatea.almaden.ibm.com umbra
This example shows that the hosts to monitor do not necessarily have to be in the same domain or on a local network. However, doing remote monitoring across a low-speed communications line is not likely to be very popular; neither with other users of that communications line nor with yourself.
Be aware that whenever you want to monitor remote hosts that are not on the same subnet as the data-consumer host, you must specify the broadcast address of the other subnets or all the host names of those hosts in the $HOME/Rsi.hosts file. The reason is that IP broadcasts do not propagate through IP routers or gateways.
The following example illustrates a situation where you want to do broadcasting on all local interfaces, want to broadcast on the subnet identified by the broadcast address 129.49.143.255, and also want to invite the host called umbra. (The subnet mask corresponding to the broadcast address in this example is 255.255.240.0 and the range of addresses covered by the broadcast is 129.49.128.0 - 129.49.143.255.)
129.49.143.255
If the RSiInvite subroutine detects that the name server is inoperational or has abnormally long response time, it returns the Internet addresses of hosts rather than the host names. If the name server fails after the list of hosts is partly built, the same host may appear twice, once with its Internet address and once with its host name.
The execution time of the RSiInvite subroutine depends primarily on the number of broadcast addresses you place in the $HOME/Rsi.hosts file. Each broadcast address increases the execution time with roughly 50 milliseconds plus the time required to process the responses. The minimum execution time of the subroutine is roughly 1.5 seconds, during which time your application only gets control if callback functions are specified and if packets arrive that must be given to those callback functions.
Another sample program written to the data-consumer API is the program chmon. Source code to the program is in /usr/samples/perfmgr/chmon.c. The chmon program is also stored as an executable during the installation of the Manager component. This program uses the API and the curses programming interface to create a screen full of statistics as shown below:
Data-Consumer API Remote Monitor for host Tue Apr 14 09:09:05
1992
CHMON Sample Program *** birte *** Interval: 5 seconds
% CPU EVENTS/QUEUES FILE/TTY
Kernel 13.3 |#### | Pswitch 1295 Readch 24589
User 23.7 |####### | Syscall 6173 Writech 1646
Wait 6.5 |## | Reads 487 Rawin 0
Idle 56.1 |################ | Writes 143 Ttyout 106
Forks 1 Igets 1763
PAGING counts PAGING SPACE REAL MEM 48MB Execs 1 Namei 809
Faults 131 % Used 33.7 % Comp 68.0 Runqueue 1 Dirblk 174
Steals 0 % Free 66.2 % NonComp 15.0 Swapqueue 0 Reads 48
Reclaim 0 Size,MB 96 % Client 4.0 Writes 143
PAGING page/s DISK Read Write % NETWORK Read Write
Pgspin 0 ACTIVITY KB/sec KB/sec Busy ACTIVITY KB/sec KB/sec
Pgspout 0 hdisk0 0.0 35.1 15.7 lo0 1.1 1.1
Pagein 0 hdisk1 0.0 0.0 0.0 tr0 1.1 0.0
Pageout 11 hdisk2 0.0 9.5 3.5
Sios 10 cd1 0.0 0.0 0.0
Process wait (514) %cpu 63.2, PgSp: 0.0mb, uid:
Process xlcentry (12657) %cpu 58.0, PgSp: 1.1mb, uid: birte
Process make (21868) %cpu 15.0, PgSp: 0.2mb, uid: birte
Process make (5998) %cpu 15.0, PgSp: 0.1mb, uid: birte
The chmon command line is:
chmon[-iseconds_interval][-pno_of_processes][hostname]
where:
The sample program exits after 2,000 observations have been taken, or when you type the letter "q" in its window.
Add a single set of peer statistics to an already defined SpmiHotSet.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiHotVals *RSiAddSetHot(rhandle, HotSet, StatName,
GrandParent,
maxresp, threshold, frequency, feed_type,
except_type, severity, trap_no)
RSiHandle rhandle;
struct SpmiHotSet *HotSet;
char *StatName;
cx_handle GrandParent;
int maxresp;
int threshold;
int frequency;
int feed_type;
int excp_type;
int severity;
int trap_no;
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
HotSet
Specifies a pointer to a valid structure of type SpmiHotSet
as created by the RSiCreateHotSet
subroutine call.
StatName
Specifies the name of the statistic within the subcontexts (peer contexts)
of the context identified by the GrandParent parameter.
GrandParent
Specifies a valid cx_handle handle as obtained by another subroutine
call. The handle must identify a context with at least one subcontext,
which contains the statistic identified by the StatName parameter.
If the context specified is one of the RTime contexts, no subcontext
need to be created at the time the SpmiAddSetHot subroutine call
is issued; the presence of the metric identified by the StatName
parameter is checked against the context class description.
If the context specified has or may have multiple levels of instantiable context below it (such as the FS and RTime/ARM contexts), the metric is only searched for at the lowest context level. The SpmiHotSet created is a pseudo hotvals structure used to link together a peer group of SpmiHotVals structures, which are created under the covers, one for each subcontext of the GrandParent context. In the case of RTime/ARM, if additional contexts are later added under the GrandParent contexts, additional hotsets are added to the peer group. This is transparent to the application program, except that the RSiGetHotItem subroutine call will return the peer group SpmiHotVals pointer rather than the pointer to the pseudo structure.
Note that specifying a specific volume group context (such as FS/rootvg) or a specific application context (such as RTime/ARN/armpeek) is still valid and won't involve creation of pseudo SpmiHotVals structures.
maxresp
Must be non-zero if excp_type specifies that exceptions or SNMP
traps must be generated. If specified as zero, indicates that all SpmiHotItems
that meet the criteria specified by threshold must be returned,
up-to a maximum of maxresp items. If both exceptions/traps and feeds
are requested, the maxresp value is used to cap the number of
exceptions/alerts
as well as the number of items returned. If feed_type is specified
as SiHotAlways, the maxresp parameter is still used to return
at most maxresp items.
Where the GrandParent argument specifies a context that has multiple levels of instantiable contexts below it, the maxresp is applied to each of the lowest level contexts above the the actual peer contexts at a time. For example, if the GrandParent context is FS (file systems) and the system has three volume groups, then a maxresp value of 2 could cause up to a maximum of 2 x 3 = 6 responses to be generated.
threshold
Must be non-zero if excp_type specifies that exceptions or SNMP
traps must be generated. If specified as zero, indicates that all values
read qualify to be returned in feeds. The value specified is compared to
the data value read for each peer statistic. If the data value exceeds
the threshold, it qualifies to be returned as an SpmiHotItems
element in the SpmiHotVals structure. If the threshold is
specified as a negative value, the value qualifies if it is lower than
the numeric value of threshold. If feed_type is specified
as SiHotAlways, the threshold value is ignored for feeds. For peer
statistics of type SiCounter, the threshold must be specified
as a rate per second; for SiQuantity statistics the threshold
is specified as a level.
frequency
Must be non-zero if excp_type specifies that exceptions or SNMP
traps must be generated. Ignored for feeds. Specifies the minimum number
of minutes that must expire between any two exceptions/traps generated
from this SpmiHotVals structure.
This value must be specified as no less than 5 minutes.
feed_type
Specifies if feeds of SpmiHotItems should be returned for this
SpmiHotVals structure. The following values are valid:
excp_type
Controls the generation of exception data packets and/or the generation
of SNMP Traps from xmservd. Note that these types of packets
and traps can only actually be sent if xmservd is running. Because
of this, exception packets and SNMP traps are only generated as long as
xmservd is active. Traps can only be generated on AIX systems. The
conditions for generating exceptions and traps are controlled by the
threshold
and frequency parameters. The following values are valid for
excp_type:
severity
Required to be positive and greater than zero if exceptions are generated,
otherwise specify as zero. Used to assign a severity code to the exception
for display by exmon.
trap_no
Required to be positive and greater than zero if SNMP traps are generated,
otherwise specify as zero. Used to assign the trap number in the generated
SNMP trap.
If successful, the subroutine returns a pointer to a structure of type struct SpmiHotVals. If an error occurs, NULL is returned and an error text may be placed in the external character array RSiEMsg. If you attempt to add more values to a statset than the current local buffer size allows, RSiErrno is set to RSiTooMany. If you attempt to add more values than the buffer size of the remote host's xmservd daemon allows, RSiErrno is set to RSiBadStat and the status field in the returned packet is set to too_many_values.
The external integer RSiMaxValues holds the maximum number of values acceptable with the data-consumer's buffer size.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateHotSetsubroutine , RSiOpen subroutine .
Changes the frequency at which the xmservd on the host identified by the first argument daemon is sending data_feed packets for a statset.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiChangeFeed(rhandle, statset, msecs) RSiHandle rhandle;struct SpmiStatSet *statset;int msecs;
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
statset
Must be a pointer to a structure of type struct SpmiStatSet,
which was previously returned by a successful RSiCreateStatSet
subroutine call. Data feeding must have been started for this SpmiStatSet
via a previous RSiStartFeed subroutine
call.
msecs
The number of milliseconds between the sending of data_feed
packets. This number is rounded to a multiple of min_remote_int
milliseconds by the xmservd daemon on the remote host. This minimum
interval can be modified through the -i command line interval to
xmservd.
If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateStatSet subroutine , RSiOpen subroutine , RSiStartFeed subroutine .
Changes the frequency at which the xmservd on the host identified by the first argument daemon is sending hot_feed packets for a statset or checking if exceptions or SNMP traps should be generated.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiChangeFeed(rhandle, hotset, msecs) RSiHandle rhandle;struct SpmiHotSet *hotset;int msecs;
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
hotset
Must be a pointer to a structure of type struct SpmiHotSet,
which was previously returned by a successful RsiCreateHotSet
subroutine call. Data feeding must have been started for this SpmiHotSet
via a previous RSiStartHotFeed subroutine
call.
msecs
The number of milliseconds between the sending of Hot_feed packets.
This number is rounded to a multiple of min_remote_int milliseconds
by the xmservd daemon on the remote host. This minimum interval
can be modified through the -i command line interval to
xmservd.
If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateHotSet subroutine , RSiOpen subroutine , RSiStartHotFeed subroutine .
Terminates the RSI interface for a remote host connection.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
void RSiClose(rhandle) RSiHandle rhandle;
The RSiClose subroutine is responsible for:
A successful RSiOpen subroutine creates tables on the remote host it was issued against. Therefore, a data consumer program that has issued successful RSiOpen subroutine calls should issue an RSiClose subroutine call for each RSiOpen call before the program exits so that the tables in the remote xmservd daemon can be released.
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
The macro RSiIsOpen can be used to test whether an RSI handle is open. It takes an RSiHandle as argument and returns true (1) if the handle is open, otherwise false (0).
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiInit subroutine, RSiOpen subroutine.
Creates an empty hotset on the remote host identified by the argument.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiHotSet *RSiCreateHotSet(rhandle) RSiHandle rhandle;
The RSiCreateHotSet subroutine allocates an SpmiHotSet structure. The structure is initialized as an empty SpmiHotSet and a pointer to the SpmiHotSet structure is returned.
The SpmiHotSet structure provides the anchor point to a set of peer statistics and must exist before the RSiAddSetHot subroutine can be successfully called.
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
The RSiCreateHotSet subroutine returns a pointer to a structure of type SpmiHotSet if successful. If unsuccessful, the subroutine returns a NULL value.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine , RSiAddSetHot subroutine .
Creates an empty statset on the remote host identified by the argument.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiStatSet *RSiCreateStatSet(rhandle) RSiHandle rhandle;
The RSiCreateStatSet subroutine allocates an SpmiStatSet structure. The structure is initialized as an empty SpmiStatSet and a pointer to the SpmiStatSet structure is returned.
The SpmiStatSet structure provides the anchor point to a set of statistics and must exist before the RSiPathAddSetStat subroutine can be successfully called.
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
The RSiCreateStatSet subroutine returns a pointer to a structure of type SpmiStatSet if successful. If unsuccessful, the subroutine returns a NULL value.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine , RSiPathAddSetStat subroutine .
Deletes a single set of peer statistics identified by an SpmiHotVals structure from an SpmiHotSet.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiDelSetHot(rhandle, hsp, hvp) RSiHandle rhandle;struct SpmiHotSet *hsp;struct SpmiHotVals *hvp;
The RSiDelSetHot subroutine performs the following actions:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
hsp
Must be a pointer to a structure type struct SpmiHotSet,
which was previously returned by a successful RSiCreateHotSet
subroutine call.
hvp
Must be a handle of type struct SpmiHotVals
as returned by a successful RSiAddSetHot
subroutine call. You can not specify an SpmiHotVals that was internally
generated by the Spmi library code as described under the GrandParent
parameter to RSiAddSetHot.
If successful, the subroutine returns a zero value; otherwise it returns a non-zero value and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateHotSet subroutine , RSiOpen subroutine , RSiAddSetHot subroutine .
Deletes a single statistic identified by an SpmiStatVals pointer from an SpmiStatSet.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiDelSetStat(rhandle, ssp, svp) RSiHandle rhandle;struct SpmiStatSet *ssp;struct SpmiStatVals *svp;
The RSiDelSetStat subroutine performs the following actions:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
ssp
Must be a pointer to a structure type struct SpmiStatSet,
which was previously returned by a successful RSiCreateStatSet
subroutine call.
svp
Must be a handle of type struct SpmiStatVals
as returned by a successful RSiPathAddSetStat
subroutine call.
If successful, the subroutine returns a zero value; otherwise it returns a non-zero value and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateStatSet subroutine , RSiOpen subroutine , RSiPathAddSetStat subroutine .
Returns the first subcontext of an SpmiCx context.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiCxLink *RSiFirstCx(rhandle, context, name, descr) RSiHandle rhandle; cx_handle *context; char **name; char **descr;
The RSiFirstCx subroutine performs the following actions:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
context
Must be a handle of type cx_handle, which was previously returned
by a successful RSiPathGetCx subroutine
call.
name
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the short name of the subcontext is returned in the
character array pointer.
descr
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the description of the subcontext is returned in the
character array pointer.
If successful, the subroutine returns a pointer to a structure of type struct SpmiCxLink. If an error occurs or if the context doesn't contain subcontexts, NULL is returned and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiNextCx subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .
Returns the first statistic of an SpmiCx context.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiStatLink *RSiFirstStat(rhandle, context, name, descr) RSiHandle rhandle; cx_handle *context; char **name; char **descr;
The RSiFirstStat subroutine performs the following actions:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
context
Must be a handle of type cx_handle, which was previously returned
by a successful RSiPathGetCx subroutine
call.
name
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the short name of the statistics value is returned
in the character array pointer.
descr
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the description of the statistics value is returned
in the character array pointer.
If successful, the subroutine returns a pointer to a structure of type struct SpmiStatLink. If an error occurs, NULL is returned and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiNextStat subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .
Locates and decodes the next SpmiHotItems element at the current position in an incoming data packet of type hot_feed.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiHotVals *RSiGetHotItem(rhandle, HotSet, index, value, absvalue, name) RSiHandle rhandle; struct SpmiHotSet **HotSet; int *index; float *value; flost absvalue; char **name;
The RSiGetHotItem subroutine locates the SpmiHotItems structure in the hot_feed data packet indexed by the value of the index parameter. The subroutine returns a NULL value if no further SpmiHotItems structures are found. The RSiGetHotItem subroutine should only be executed after a successful call to the RSiGetHotSet subroutine.
The RSiGetHotItem subroutine is designed to be used for walking all SpmiHotItems elements returned in a hot_feed data packet. Since the data packet may contain elements belonging to more than one SpmiHotSet, the index is purely abstract and is only used to keep position. By feeding the updated integer pointed to by index back to the next call, the walking of the hot_feed packet can be done in a tight loop. Succesful calls to RSiGetHotItem will decode each SpmiHotItems element and return the data value in value and the name of the peer context that owns the corresponding statistic in name.
The RSiGetHotItem subroutine returns a pointer to the current SpmiHotVals structure within the hotset. If no more SpmiHotItems elements are available, the subroutine returns a NULL value. The structure returned contains the data, such as threshold, which may be relevant for presentation of the results of an SpmiGetHotSet subroutine call to end-users. In the returned SpmiHotVals structure, all fields contain the correct values as declared, except for the following:
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine , RSiCreateHotSet subroutine .
Returns a pointer to a valid SpmiStatVals structure for a given SpmiStatVals pointer by extraction from a data_feed packet. This subroutine call should only be issued from a callback function after it has been verified that a data_feed packet was received from the host identified by the first argument.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiStatVals RSiGetRawValue(rhandle, svp, index) RSiHandle rhandle; struct SpmiStatVals *svp; int *index;
The RSiGetRawValue subroutine performs the following:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
svp
A handle of type struct SpmiStatVals,
which was previously returned by a successful RSiPathAddSetStat
subroutine call.
index
A pointer to an integer variable. When the subroutine call succeeds,
the index into the ValsSet array of the data feed packet is returned.
The index corresponds to the element that matches the svp argument
to the subroutine.
If successful, the subroutine returns a pointer; otherwise NULL is returned and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiGetRawValue subroutine , RSiOpen subroutine , RSiPathAddSetStat subroutine .
Returns a data value for a given SpmiStatVals pointer by extraction from the data_feed packet. This subroutine call should only be issued from a callback function after it has been verified that a data_feed packet was received from the host identified by the first argument.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
float RSiGetValue(rhandle, svp) RSiHandle rhandle; struct SpmiStatVals *svp;
The RSiGetValue subroutine provides the following:
rhandle
Must be an RSiHandle, previously initialized by the RSiOpen
subroutine.
svp
A handle of type struct SpmiStatVals,
which was previously returned by a successful RSiPathAddSetStat
subroutine call.
If successful, the subroutine returns a non-negative value; otherwise it returns a negative value less than or equal to -1.0. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine , RSiPathAddSetStat subroutine .
Allocates or changes the table of RSi handles.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
RSiHandle RSiInit(count) int count;
Before any other RSi call is executed, a data-consumer program must issue the RSiInit call. Its purpose is to either:
count
Must specify the number of elements in the array of RSi handles. If
the call is used to expand a previously allocated array, this argument
must be larger than the current number of array elements. It must always
be larger than zero. You should specify the size of the array to be at
least as large as the number of hosts your data-consumer program can talk
to at any point in time.
If successful, the subroutine returns the address of the allocated array. If an error occurs, an error text is placed in the external character array RSiEMsg and the subroutine returns NULL. When used to increase the size of a previously allocated array, the subroutine first allocates the new array, then moves the entire old array to the new area. Application programs should, therefore, refer to elements in the RSi handle array by index rather than by address if they anticipate the need for expanding the array. The array only needs to be expanded if the number of remote hosts a data-consumer program talks to might increase over the life of the program.
An application that calls RSiInit repeatedly needs to preserve the previous address of the RSiHandle array while the RSiInit call is re-executed. After the call has completed successfully, the calling program should free the previous array using the free subroutine.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiClose subroutine .
Creates (instantiates) all subcontexts of an SpmiCx context object.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiInstantiate(rhandle, context) RSiHandle rhandle; cx_handle *context;
The RSiInstantiate subroutine performs the following actions:
The RSiInstantiate subroutine explicitly instantiates the subcontexts of an instantiable context. If the context is not instantiable, do not call the RSiInstantiate subroutine.
rhandle
Must point to a structure of type RSiHandle, which was previously
initialized by the RSiOpen subroutine.
context
Must be a handle of type cx_handle, which was previously returned
by a successful RSiPathGetCx subroutine
call.
If successful, the subroutine returns a zero value; otherwise it returns an error code as defined in SiError and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiFirstCx subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .
Invites data suppliers on the network to identify themselves and returns a table of data-supplier host names.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
char **RSiInvite(resy_callb, excp_callb) int (*resy_callb)(); int (*excp_callb)();
The RSiInvite subroutine call broadcasts are_you_there messages on the network to provoke xmservd daemons on remote hosts to respond and returns a table of all responding hosts.
The arguments to the subroutine are:
resy_callb
Must be either NULL or a pointer to a function that processes
i_am_back
packets as they are received from the xmservd daemons on remote
hosts for the duration of the RSiInvite subroutine call. When the
callback function is invoked it is passed three arguments as described
below.
If this argument is specified as NULL, a callback function internal to the RSiInvite subroutine receives any i_am_back packets and uses them to build the table of host names the function returns.
excp_callb
Must be NULL or a pointer to a function that processes except_rec
packets as they are received from the xmservd daemons on remote
hosts. If a NULL pointer is passed, your application does not receive
except_rec
messages. When this callback function is invoked it is passed three arguments
as described below.
This argument always overrides the corresponding argument of any previous RSiInvite or RSiOpen call and may itself be overridden by subsequent executions of either. In this way, your application can turn exception monitoring on and off. For an RSiOpen to override the exception processing specified by a previous open call, the connection must first be closed with the RSiClose call. That's because an RSiOpen against an already active handle is treated as a no-operation.
The resy_callb and excp_callb functions in your application are called with the following three arguments:
If successful, the subroutine returns an array of character pointers, each of which contains a host name of a host that responded to the invitation. The returned host names are actually constructed as two "words" with the first one being the host name returned by the host in response to an are_you_there request; the second one being the character form of the host's Internet address. The two "words" are separated by one or more blanks. This format is suitable as an argument to the RSiOpen subroutine call. In addition, the external integer variable RSiInvTabActive contains the number of host names found. The returned pointer to an array of host names must not be freed by the subroutine call. The calling program should not assume that the pointer returned by this subroutine call remains valid after subsequent calls to RSiInvite. If the call is not successful, an error text is placed in the external character array RSiEMsg, an error number is placed in RSiErrno, and the subroutine returns NULL.
The list of host names returned by RSiInvite does not include the hosts your program has already established a connection with through an RSiOpen call. Your program is responsible for keeping track of such hosts. If you need a list of both sets of hosts, either let the RSiInvite call be the first one issued from your program or merge the list of host names returned by the call with the list of hosts to which you have connections.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine .
Allows an application to suspend execution and wait to get awakened when data feeds arrive.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
void RSiMainLoop(msecs) int msecs;
The RSiMainLoop subroutine:
To work properly, the RSiMainLoop subroutine requires that at least one RSiOpen call has been successfully completed and that the connection has not been closed.
msecs
The minimum elapsed time in milliseconds that the subroutine should
continue to attempt receives before returning to the caller. Notice that
your program releases control for as many milliseconds you specify but
that the callback functions defined on the RSiOpen call may be called
repetitively during that time.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine .
Returns the next subcontext of an SpmiCx context.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiCxLink *RSiNextCx(rhandle, context, link, name, descr) RSiHandle rhandle; cx_handle *context; struct SpmiCxLink *link; char **name; char **descr;
The RSiNextCx subroutine:
rhandle
Must point to a structure of type RSiHandle, which was previously
initialized by the RSiOpen subroutine.
context
Must be a handle of type cx_handle, which was previously returned
by a successful RSiPathGetCx subroutine
call.
link
Must be a pointer to a structure of type struct SpmiCxLink,
which was previously returned by a successful RSiFirstCx
or RSiNextCx subroutine call.
name
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the short name of the subcontext is returned in the
character array pointer.
descr
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the description of the subcontext is returned in the
character array pointer.
If successful, the subroutine returns a pointer to a structure of type struct SpmiCxLink. If an error occurs, or if no more subcontexts exist for the context, NULL is returned and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiFirstCx subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .
Returns the next statistic of an SpmiCx context.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiStatLink *RSiNextStat(rhandle, context, link, name, descr) RSiHandle rhandle; cx_handle *context; struct SpmiStatLink *link; char **name; char **descr;
The RSiNextStat subroutine:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
context
Must be a handle of type cx_handle, which was previously returned
by a successful RSiPathGetCx subroutine
call.
link
Must be a pointer to a structure of type struct SpmiStatLink,
which was previously returned by a successful RSiFirstStat
or RSiNextStat subroutine call.
name
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the short name of the statistics value is returned
in the character array pointer.
descr
Must be a pointer to a pointer to a character array. The pointer must
be initialized to point at a character array pointer. When the subroutine
call is successful, the description of the statistics value is returned
in the character array pointer.
If successful, the subroutine returns a pointer to a structure of type struct SpmiStatLink. If an error occurs, or if no more statistics exists for the context, NULL is returned and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiFirstStat subroutine , RSiOpen subroutine , RSiPathGetCx subroutine .
Initializes the RSi interface for a remote host.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiOpen(rhandle, wait, bufsize, hostID, feed_callb,
resy_callb, excp_callb)
RSiHandle rhandle;
int wait;
int bufsize;
char *hostID;
int (*feed_callb)();
int (*resy_callb)();
int (*excp_callb)();
The RSiOpen subroutine performs the following actions:
The arguments to the subroutine are:
rhandle
Must point to an element of the RSiHandleStruct array, which
is returned by a previous RSiInit call. If
the subroutine is successful the structure is initialized and ready to
use as a handle for subsequent RSi interface subroutine calls.
wait
Must specify the timeout in milliseconds that the RSi interface shall
wait for a response when using the request-response functions. On LANs,
a reasonable value for this argument is 100 milliseconds. If the response
is not received after the specified wait time, the library subroutines
retry the receive operation until five times the wait time has elapsed
before returning a timeout indication. The wait time must be zero or more
milliseconds.
bufsize
Specifies the maximum buffer size to be used for constructing network
packets. This size must be at least 4,096 bytes. The buffer size determines
the maximum packet length that can be received by your program and sets
the limit for the number of data values that can be received in one
data_feed
packet. There's no point in setting the buffer size larger than that of
the xmservd daemon since both must be able to handle the packets.
If you need large sets of values, you can use the command line argument
-b of xmservd to increase its buffer size up to 16,384 bytes.
The fixed part of a data_feed packet is 104 bytes and each value takes 32 bytes. A buffer size of 4,096 bytes allows up to 124 values per packet.
hostID
Must be a character array containing the identification of the remote
host whose xmservd daemon we want to talk to. The first "word"
of the host identification (up to the first white space) is used as the
host name. The full host identification is stored in the RSiHandle
field longname and may contain any description that helps the end
user identify the host used. The host name may be either in long format
(including domain name) or in short format.
feed_callb
Must be a pointer to a function that processes data_feed packets
as they are received from the xmservd daemon. When this callback
function is invoked, it is passed three arguments as described below.
resy_callb
Must be a pointer to a function that processes i_am_back packets
as they are received from the xmservd daemon. When this callback
function is invoked it is passed three arguments as described below.
excp_callb
Must be NULL or a pointer to a function that processes except_rec
packets as they are received from the xmservd daemon. If a NULL
pointer is passed, your application does not receive except_rec
messages. When this callback function is invoked, it is passed three arguments
as described below. This argument always overrides the corresponding argument
of any previous RSiInvite or RSiOpen
subroutine call and can itself be overridden by subsequent executions of
either. In this way, your application can turn exception monitoring on
and off. For an RSiOpen call to override the exception processing
specified by a previous open call, the connection must first be closed
with the RSiClose subroutine call.
The feed_callb, resy_callb, and excp_callb functions are called with the arguments:
RSiHandle. When a data_feed packet is received, the structure pointed to is guaranteed to represent the host sending the packet. In all other situations the RSiHandle structure may represent any of the hosts to which your application is talking.
Pointer of type pack * to the input buffer containing the received packet. In callback functions, always use this pointer rather than the pointer in the RSiHandle structure.
Pointer of type struct sockaddr_in * to the Internet address of the originating host.
If successful, the subroutine returns zero and initializes the array element of type RSiHandle pointed to by rhandle. If an error occurs, error text is placed in the external character array RSiEMsg and the subroutine returns a negative value.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiClose subroutine , RSiInvite subroutine , RSiOpen subroutine .
Add a single statistics value to an already defined SpmiStatSet.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
struct SpmiStatVals *RSiPathAddSetStat(rhandle, statset, path) RSiHandle rhandle; struct SpmiStatSet *statset; char *path;
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
statset
Must be a pointer to a structure of type struct SpmiStatSet,
which was previously returned by a successful RSiCreateStatSet
subroutine call.
path
Must be the full value path name of the statistics value to add to
the SpmiStatSet. The value path name must not include a terminating
slash. Note that value path names never start with a slash.
If successful, the subroutine returns a pointer to a structure of type struct SpmiStatVals. If an error occurs, NULL is returned and an error text may be placed in the external character array RSiEMsg. If you attempt to add more values to a statset than the current local buffer size allows, RSiErrno is set to RSiTooMany. If you attempt to add more values than the buffer size of the remote host's xmservd daemon allows, RSiErrno is set to RSiBadStat and the status field in the returned packet is set to too_many_values.
The external integer RSiMaxValues holds the maximum number of values acceptable with the data-consumer's buffer size.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateStatSet subroutine , RSiOpen subroutine .
Searches the context hierarchy for an SpmiCx context that matches a context path name.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
cx_handle *RSiPathGetCx(rhandle, path) RSiHandle rhandle; char *path;
The RSiPathGetCx subroutine performs the following actions:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
path
A path name of a context for which a handle is to be returned. The
context path name must be the full path name and must not include a terminating
slash. Note that context path names never start with a slash.
If successful, the subroutine returns a handle defined as a pointer to a structure of type cx_handle. If an error occurs, NULL is returned and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiFirstCx subroutine , RSiOpen subroutine , RSiNextCx subroutine .
Finds the full path name of a statistic identified by a SpmiStatVals pointer.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
char *RSiStatGetPath(rhandle, svp) RSiHandle rhandle; struct SpmiStatVals *svp;
The RSiStatGetPath subroutine performs the following:
The memory area pointed to by the returned pointer is freed when the RSiStatGetPath subroutine call is repeated. For each invocation of the subroutine, a new memory area is allocated and its address returned.
If the calling program needs the returned character string after issuing the RSiStatGetPath subroutine call, the program must copy the returned string to locally allocated memory before reissuing the subroutine call.
rhandle
Must be an RSiHandle, previously initialized by the RSiOpen
subroutine.
svp
Must be a handle of type struct SpmiStatVals as returned by
a successful RSiPathAddSetStat
subroutine call.
If successful, the RSiStatGetPath subroutine returns a pointer to a character array containing the full path name of the statistic. If unsuccessful, the subroutine returns a NULL value and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine , RSiPathAddSetStat subroutine .
Tells xmservd to start sending data feeds for a statset.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiStartFeed(rhandle, statset, msecs) RSiHandle rhandle; struct SpmiStatSet *statset; int msecs;
The RSiStartFeed subroutine performs the following function:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
statset
Must be a pointer to a structure of type struct SpmiStatSet,
which was previously returned by a successful RSiCreateStatSet
subroutine call.
msecs
The number of milliseconds between the sending of data_feed
packets. This number is rounded to a multiple of min_remote_int
milliseconds by the xmservd daemon on the remote host. This minimum
interval can be modified through the -i command line interval to
xmservd.
If successful, the subroutine returns zero; otherwise it returns -1 and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateStatSet subroutine , RSiOpen subroutine , RSiStopFeed subroutine .
Tells xmservd to start sending hot feeds for a hotset or to start checking for if exceptions or SNMP traps should be generated.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiStartFeed(rhandle, hotset, msecs) RSiHandle rhandle; struct SpmiHotSet *hotset; int msecs;
The RSiStartHotFeed subroutine performs the following function:
rhandle
Must be an RSiHandle, which was previously initialized by the
RSiOpen subroutine.
hotset
Must be a pointer to a structure of type struc SpmiHotSet,
which was previously returned by a successful RSiCreateHot
subroutine call.
msecs
The number of milliseconds between the sending of hot_feed packets
and/or the number of milliseconds between checks for if exceptions or
SNMP traps
should be generated. This number is rounded to a multiple of
min_remote_int
milliseconds by the xmservd daemon on the remote host. This minimum
interval can be modified through the -i command line interval to
xmservd.
If successful, the subroutine returns zero; otherwise it returns -1 and an error text may be placed in the external character array RSiEMsg.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiCreateHotSet subroutine , RSiOpensubroutine , RsiChangeHotFeed subroutine , RSiStopHotFeed subroutine .
Tells xmservd to stop sending data feeds for a statset.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiStopFeed(rhandle, statset, erase) RSiHandle rhandle; struct SpmiStatSet *statset; boolean erase;
The RSiStopFeed subroutine instructs the xmservd of a remote system to:
rhandle
Must point to a structure of type RSiHandle, which was previously
initialized by the RSiOpen subroutine.
statset
Must be a pointer to a structure of type struct SpmiStatSet,
which was previously returned by a successful RSiCreateStatSet
subroutine call. Data feeding must have been started for this SpmiStatSet
via a previous RSiStartFeed subroutine
call.
erase
If this argument is set to true, the xmservd daemon on the remote
host discards all information about the named SpmiStatSet. Otherwise
the daemon maintains its definition of the set of statistics.
If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine , RSiStartFeed subroutine .
Tells xmservd to stop sending hot feeds for a hotset and to stop checking for exception and SNMP trap generation.
RSI Library (libSpmi.a)
#include <sys/Rsi.h>
int RSiStopFeed(rhandle, hotset, erase) RSiHandle rhandle; struct SpmiHotSet *hotset; boolean erase;
The RSiStopHotFeed subroutine instructs the xmservd of a remote system to:
rhandle
Must point to a structure of type RSiHandle, which was previously
initialized by the RSiOpen subroutine.
hotset
Must be a pointer to a structure of type struct SpmiHotSet,
which was previously returned by a successful RSiCreateHotSet
subroutine call. Data feeding must have been started for this SpmiStatSet
via a previous RSiStartHotFeed subroutine
call.
erase
If this argument is set to true, the xmservd daemon on the remote
host discards all information about the named SpmiHotSet. Otherwise
the daemon maintains its definition of the set of statistics.
If successful, the subroutine returns zero, otherwise -1. A NULL error text is placed in the external character array RSiEMsg regardless of the subroutine's success or failure.
All RSI subroutines use external variables to provide error information. To access these variables, an application program must define the following external variables:
If the subroutine returns without an error, the RSiErrno variable is set to RSiOkay and the RSiEMsg character array is empty. If an error is detected, the RSiErrno variable returns an error code, as defined in the enum RSiErrorType. RSi error codes are described in List of RSi Error Codes .
This subroutine is part of the Performance Toolbox for AIX licensed product.
/usr/include/sys/Rsi.h
Declares the subroutines, data structures, handles, and macros that
an application program can use to access the RSI.
RSiOpen subroutine , RSiStartHotFeed subroutine , RSiChangeHotFeed subroutine .
All RSI subroutines use constants to define error codes. The RSI Error Code table lists the error descriptions.
| Symbolic Name | Number | Description |
| RSiTimeout | 280 | A time-out occurred while waiting for a response to a request. |
| RSiBusy | 281 | An RSiOpen subroutine was issued, but another is already active. |
| RSiSendErr | 282 | An error occurred when the library attempted to send a UDP packet with the sendto() system call. |
| RSiPollErr | 283 | A system error occurred while issuing or processing a poll() or select() system call. |
| RSiRecvErr | 284 | A system error occurred while attempting to read an incoming UDP packet with the recvfrom() syatem call. |
| RSiSizeErr | 285 | A recvfrom() system call returned a UDP packet with incorrect length or incorrect source address. |
| RSiResync | 286 | While waiting for a response to an outgoing request, one of the following
occurred and cause an error return to the calling program:
The code may also be set when a success return code ia returned to the caller, in which case it shows that either an exception packet or an i_am_back packet was processed successfully while waiting for a response. |
| RSiBadStat | 287 | A bad status code was received in the data packet received. |
| RSiBadArg | 288 | An invalid argument was passed to an RSi subroutine. |
| RSiBadHost | 289 | A valid host address can not be constructed from an IP address or the nameservice doesn't know the hostname. |
| RSiDupHost | 290 | An RSiOpen call was issued against a host but a connection is already open to a host with this IP address and a different hostname. |
| RSiSockErr | 291 | An error occurred while opening or communicating with a socket. |
| RSiNoPort | 292 | The RSi is unable to find the port number to use when inviting remote suppliers. The likely cause is that the xmquery entry is missing from the /etc/services file or the NIS (Yellow Pages) server. |
| RSiNoMatch | 293 | One of the following occurred:
|
| RSiInstErr | 294 | An error was returned when attempting to instantiate a remote context. |
| RSiNoFeed | 295 | When extracting a data value with the RSiGetValue call, the data value was marked as invalid by the remote data supplier. |
| RSiTooMany | 296 | An attempt was made to add more values to a statset than the current buffer size permits. |
| RSiNoMem | 297 | Memory allocation error. |
| RSiNotInit | 298 | An RSi call was attempted before an RSiInit call was issued. |
| RSiNoLicense | 299 | License expired or no license found. |
| RSiNotSupported | 300 | The subroutine call requires a later protocol version that the one supported by the remote system's xmservd. |